---
id: combobox
title: Combobox
description: A single input field that combines the functionality of a select and input.
---

<ComponentPreview id="Combobox" />

## Anatomy

To set up the combobox correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="combobox" />

## Examples

Learn how to use the `Combobox` component in your project. Let's take a look at the most basic example

<Example id="basic" />

### Grouping

To group related combobox items, use the `groupBy` prop on the collection and `collection.group()` to iterate the
groups.

<Example id="grouping" />

### Field

The `Field` component helps manage form-related state and accessibility attributes of a combobox. It includes handling
ARIA labels, helper text, and error text to ensure proper accessibility.

<Example id="with-field" />

### Root Provider

Use the `useCombobox` hook to create the combobox store and pass it to the `Combobox.RootProvider` component. This
allows you to have maximum control over the combobox programmatically.

<Example id="root-provider" />

> If you're using the `Combobox.RootProvider` component, you don't need to use the `Combobox.Root` component.

### Links

Use the `asChild` prop to render the combobox items as links.

<Example id="links" />

### Rehydrate Value

In some cases, where a combobox has a `defaultValue` or `value` but the `collection` is not loaded yet, here's how to
rehydrate the value and populate the input value.

<Example id="rehydrate-value" />

### Highlight Matching Text

Here's an example of highlighting the search text in combobox items based on the user's input.

<Example id="with-highlight" />

### Dynamic Items

Generate combobox items dynamically based on user input. This is useful for creating suggestions or autocomplete
functionality.

<Example id="dynamic" />

### Creatable Options

Allow users to create new options when their search doesn't match any existing items. This is useful for tags,
categories, or other custom values.

<Example id="creatable" />

<Example id="custom-object" />

## Guides

### Custom Router Links

For custom router links, you can customize the `navigate` prop on the `Combobox.Root` component.

Here's an example of using the Tanstack Router.

```tsx
import { Combobox } from '@ark-ui/react/combobox'
import { useNavigate } from '@tanstack/react-router'

function Demo() {
  const navigate = useNavigate()
  return (
    <Combobox.Root
      navigate={(e) => {
        navigate({ to: e.node.href })
      }}
    >
      {/* ... */}
    </Combobox.Root>
  )
}
```

### Custom Objects

By default, the combobox collection expects an array of objects with `label` and `value` properties. In some cases, you
may need to deal with custom objects.

Use the `itemToString` and `itemToValue` props to map the custom object to the required interface.

```tsx
const items = [
  { country: 'United States', code: 'US', flag: '🇺🇸' },
  { country: 'Canada', code: 'CA', flag: '🇨🇦' },
  { country: 'Australia', code: 'AU', flag: '🇦🇺' },
  // ...
]

const { collection } = useListCollection({
  initialItems: items,
  itemToString: (item) => item.country,
  itemToValue: (item) => item.code,
})
```

### Type-Safety

The `Combobox.RootComponent` type enables you to create closed, strongly typed wrapper components that maintain full
type safety for collection items.

This is particularly useful when building reusable combobox components with custom props and consistent styling.

```tsx
import { Combobox as ArkCombobox, type CollectionItem } from '@ark-ui/react/combobox'
import { useListCollection } from '@ark-ui/react/collection'

interface ComboboxProps<T extends CollectionItem> extends ArkCombobox.RootProps<T> {}

const Combobox: ArkCombobox.RootComponent = (props) => {
  return <ArkCombobox.Root {...props}>{/* ... */}</ArkCombobox.Root>
}
```

Then, you can use the `Combobox` component as follows:

```tsx
const App = () => {
  const { collection } = useListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  })
  return (
    <Combobox
      collection={collection}
      onValueChange={(e) => {
        // this will be strongly typed Array<{ label: string, value: string }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </Combobox>
  )
}
```

### Limit Large Datasets

The recommended way of managing large lists is to use the `limit` property on the `useListCollection` hook. This will
limit the number of rendered items in the DOM to improve performance.

```tsx {3}
const { collection } = useListCollection({
  initialItems: items,
  limit: 10,
})
```

### Available height and width

The following css variables are exposed to the `Combobox.Positioner` which you can use to style the `Combobox.Content`

```css
/* width of the combobox control */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:

```css
[data-scope='combobox'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

<ComponentTypes id="combobox" />

### Context

These are the properties available when using `Combobox.Context`, `useComboboxContext` hook or `useCombobox` hook.

<ContextType id="combobox" />

## Accessibility

Complies with the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).

### Keyboard Support

<KeyBindingsTable id="combobox" />
